/**
* getCurrentExtension:
*
- * Returns the current extension, or null if not called from an extension.
+ * @returns {?object} - The current extension, or null if not called from
+ * an extension.
*/
function getCurrentExtension() {
let stack = (new Error()).stack.split('\n');
/**
* initTranslations:
- * @domain: (optional): the gettext domain to use
+ * @param {string=} domain - the gettext domain to use
*
* Initialize Gettext to load translations from extensionsdir/locale.
* If @domain is not provided, it will be taken from metadata['gettext-domain']
/**
* getSettings:
- * @schema: (optional): the GSettings schema id
+ * @param {string=} schema - the GSettings schema id
+ * @returns {Gio.Settings} - a new settings object for @schema
*
* Builds and returns a GSettings schema for @schema, using schema files
* in extensionsdir/schemas. If @schema is omitted, it is taken from
/**
* versionCheck:
- * @required: an array of versions we're compatible with
- * @current: the version we have
+ * @param {string[]} required - an array of versions we're compatible with
+ * @param {string} current - the version we have
+ * @returns {bool} - true if @current is compatible with @required
*
* Check if a component is compatible for an extension.
* @required is an array, and at least one version must match.
let _loginManager = null;
/**
- * LoginManager:
+ * getLoginManager:
* An abstraction over systemd/logind and ConsoleKit.
+ * @returns {object} - the LoginManager singleton
*
*/
function getLoginManager() {
/**
* _select:
- * @app: index of the app to select
- * @window: (optional) index of which of @app's windows to select
- * @forceAppFocus: optional flag, see below
+ * @param {number} app: index of the app to select
+ * @param {number=} window: index of which of @app's windows to select
+ * @param {bool} forceAppFocus: optional flag, see below
*
* Selects the indicated @app, and optional @window, and sets
* this._thumbnailsFocused appropriately to indicate whether the
/**
* appendMessage:
- * @message: An object with the properties:
- * text: the body of the message,
- * messageType: a #Tp.ChannelTextMessageType,
- * sender: the name of the sender,
- * timestamp: the time the message was sent
- * direction: a #NotificationDirection
+ * @param {Object} message: An object with the properties
+ * {string} message.text: the body of the message,
+ * {Tp.ChannelTextMessageType} message.messageType: the type
+ * {string} message.sender: the name of the sender,
+ * {number} message.timestamp: the time the message was sent
+ * {NotificationDirection} message.direction: a #NotificationDirection
*
- * @noTimestamp: Whether to add a timestamp. If %true, no timestamp
- * will be added, regardless of the difference since the
- * last timestamp
+ * @param {bool} noTimestamp: Whether to add a timestamp. If %true,
+ * no timestamp will be added, regardless of the difference since
+ * the last timestamp
*/
appendMessage(message, noTimestamp) {
let messageBody = GLib.markup_escape_text(message.text, -1);
/**
* _append:
- * @props: An object with the properties:
- * body: The text of the message.
- * group: The group of the message, one of:
+ * @param {Object} props: An object with the properties:
+ * {string} props.body: The text of the message.
+ * {string} props.group: The group of the message, one of:
* 'received', 'sent', 'meta'.
- * styles: Style class names for the message to have.
- * timestamp: The timestamp of the message.
- * noTimestamp: suppress timestamp signal?
+ * {string[]} props.styles: Style class names for the message to have.
+ * {number} props.timestamp: The timestamp of the message.
+ * {bool} props.noTimestamp: suppress timestamp signal?
*/
_append(props) {
let currentTime = Date.now() / 1000;
/**
* startDrag:
- * @stageX: X coordinate of event
- * @stageY: Y coordinate of event
- * @time: Event timestamp
+ * @param {number} stageX: X coordinate of event
+ * @param {number} stageY: Y coordinate of event
+ * @param {number} time: Event timestamp
+ * @param {Clutter.EventSequence=} sequence: Event sequence
+ * @param {Clutter.InputDevice=} device: device that originated the event
*
* Directly initiate a drag and drop operation from the given actor.
* This function is useful to call if you've specified manualMode
/**
* makeDraggable:
- * @actor: Source actor
- * @params: (optional) Additional parameters
+ * @param {Clutter.Actor} actor: Source actor
+ * @param {Object=} params: Additional parameters
+ * @returns {Object} a new Draggable
*
* Create an object which controls drag and drop for the given actor.
*
/**
* openExtraSpace:
- * @sourceItem: the item for which to create extra space
- * @side: where @sourceItem should be located relative to the created space
- * @nRows: the amount of space to create
+ * @param {Clutter.Actor} sourceItem: item for which to create extra space
+ * @param {St.Side} side: where @sourceItem should be located relative to
+ * the created space
+ * @param {number} nRows: the amount of space to create
*
* Pan view to create extra space for @nRows above or below @sourceItem.
*/
/**
* highlight:
- * @window: actor to highlight
+ * @param {Clutter.Actor=} window: actor to highlight
*
* Highlights the indicated actor and unhighlights any other
* currently-highlighted actor. With no arguments or a false/null
/**
* setActive:
* Show/hide all the zoom regions.
- * @activate: Boolean to activate or de-activate the magnifier.
+ * @param {bool} activate: Boolean to activate or de-activate the magnifier.
*/
setActive(activate) {
let isActive = this.isActive();
/**
* isActive:
- * @return Whether the magnifier is active (boolean).
+ * @returns {bool} Whether the magnifier is active.
*/
isActive() {
// Sufficient to check one ZoomRegion since Magnifier's active
/**
* isTrackingMouse:
- * Is the magnifier tracking the mouse currently?
+ * @returns {bool} whether the magnifier is currently tracking the mouse
*/
isTrackingMouse() {
return !!this._mouseTrackingId;
* scrollToMousePos:
* Position all zoom regions' ROI relative to the current location of the
* system pointer.
- * @return true.
+ * @returns {bool} true.
*/
scrollToMousePos() {
let [xMouse, yMouse] = global.get_pointer();
/**
* createZoomRegion:
* Create a ZoomRegion instance with the given properties.
- * @xMagFactor: The power to set horizontal magnification of the
- * ZoomRegion. A value of 1.0 means no magnification. A
- * value of 2.0 doubles the size.
- * @yMagFactor: The power to set the vertical magnification of the
- * ZoomRegion.
- * @roi Object in the form { x, y, width, height } that
- * defines the region to magnify. Given in unmagnified
- * coordinates.
- * @viewPort Object in the form { x, y, width, height } that defines
- * the position of the ZoomRegion on screen.
- * @return The newly created ZoomRegion.
+ * @param {number} xMagFactor:
+ * The power to set horizontal magnification of the ZoomRegion. A value
+ * of 1.0 means no magnification, a value of 2.0 doubles the size.
+ * @param {number} yMagFactor:
+ * The power to set the vertical magnification of the ZoomRegion.
+ * @param {{x: number, y: number, width: number, height: number}} roi:
+ * The reg Object that defines the region to magnify, given in
+ * unmagnified coordinates.
+ * @param {{x: number, y: number, width: number, height: number}} viewPort:
+ * Object that defines the position of the ZoomRegion on screen.
+ * @returns {ZoomRegion} the newly created ZoomRegion.
*/
createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) {
let zoomRegion = new ZoomRegion(this, this._cursorRoot);
* addZoomRegion:
* Append the given ZoomRegion to the list of currently defined ZoomRegions
* for this Magnifier instance.
- * @zoomRegion: The zoomRegion to add.
+ * @param {ZoomRegion} zoomRegion: The zoomRegion to add.
*/
addZoomRegion(zoomRegion) {
if (zoomRegion) {
/**
* getZoomRegions:
* Return a list of ZoomRegion's for this Magnifier.
- * @return: The Magnifier's zoom region list (array).
+ * @returns {number[]} The Magnifier's zoom region list.
*/
getZoomRegions() {
return this._zoomRegions;
/**
* setCrosshairsVisible:
* Show or hide the cross hair.
- * @visible Flag that indicates show (true) or hide (false).
+ * @param {bool} visible: Flag that indicates show (true) or hide (false).
*/
setCrosshairsVisible(visible) {
if (visible) {
/**
* setCrosshairsColor:
* Set the color of the crosshairs for all ZoomRegions.
- * @color: The color as a string, e.g. '#ff0000ff' or 'red'.
+ * @param {string} color: The color as a string, e.g. '#ff0000ff' or 'red'.
*/
setCrosshairsColor(color) {
if (this._crossHairs) {
/**
* getCrosshairsColor:
* Get the color of the crosshairs.
- * @return: The color as a string, e.g. '#0000ffff' or 'blue'.
+ * @returns {string} The color as a string, e.g. '#0000ffff' or 'blue'.
*/
getCrosshairsColor() {
if (this._crossHairs) {
/**
* setCrosshairsThickness:
* Set the crosshairs thickness for all ZoomRegions.
- * @thickness: The width of the vertical and horizontal lines of the
- * crosshairs.
+ * @param {number} thickness: The width of the vertical and
+ * horizontal lines of the crosshairs.
*/
setCrosshairsThickness(thickness) {
if (this._crossHairs)
/**
* getCrosshairsThickness:
* Get the crosshairs thickness.
- * @return: The width of the vertical and horizontal lines of the
- * crosshairs.
+ * @returns {number} The width of the vertical and horizontal
+ * lines of the crosshairs.
*/
getCrosshairsThickness() {
if (this._crossHairs)
/**
* setCrosshairsOpacity:
- * @opacity: Value between 0.0 (transparent) and 1.0 (fully opaque).
+ * @param {number} opacity: Value between 0.0 (transparent)
+ * and 1.0 (fully opaque).
*/
setCrosshairsOpacity(opacity) {
if (this._crossHairs)
/**
* getCrosshairsOpacity:
- * @return: Value between 0.0 (transparent) and 1.0 (fully opaque).
+ * @returns {number} Value between 0.0 (transparent) and 1.0 (fully opaque).
*/
getCrosshairsOpacity() {
if (this._crossHairs)
/**
* setCrosshairsLength:
* Set the crosshairs length for all ZoomRegions.
- * @length: The length of the vertical and horizontal lines making up the
- * crosshairs.
+ * @param {number} length: The length of the vertical and horizontal
+ * lines making up the crosshairs.
*/
setCrosshairsLength(length) {
if (this._crossHairs)
/**
* getCrosshairsLength:
* Get the crosshairs length.
- * @return: The length of the vertical and horizontal lines making up the
- * crosshairs.
+ * @returns {number} The length of the vertical and horizontal
+ * lines making up the crosshairs.
*/
getCrosshairsLength() {
if (this._crossHairs)
/**
* setCrosshairsClip:
* Set whether the crosshairs are clipped at their intersection.
- * @clip: Flag to indicate whether to clip the crosshairs.
+ * @param {bool} clip: Flag to indicate whether to clip the crosshairs.
*/
setCrosshairsClip(clip) {
if (!this._crossHairs)
/**
* getCrosshairsClip:
* Get whether the crosshairs are clipped by the mouse image.
- * @return: Whether the crosshairs are clipped.
+ * @returns {bool} Whether the crosshairs are clipped.
*/
getCrosshairsClip() {
if (this._crossHairs) {
/**
* setActive:
- * @activate: Boolean to show/hide the ZoomRegion.
+ * @param {bool} activate: Boolean to show/hide the ZoomRegion.
*/
setActive(activate) {
if (activate == this.isActive())
/**
* isActive:
- * @return Whether this ZoomRegion is active (boolean).
+ * @returns {bool} Whether this ZoomRegion is active
*/
isActive() {
return this._magView != null;
/**
* setMagFactor:
- * @xMagFactor: The power to set the horizontal magnification factor to
- * of the magnified view. A value of 1.0 means no
- * magnification. A value of 2.0 doubles the size.
- * @yMagFactor: The power to set the vertical magnification factor to
- * of the magnified view.
+ * @param {number} xMagFactor: The power to set the horizontal
+ * magnification factor to of the magnified view. A value of 1.0
+ * means no magnification. A value of 2.0 doubles the size.
+ * @param {number} yMagFactor: The power to set the vertical
+ * magnification factor to of the magnified view.
*/
setMagFactor(xMagFactor, yMagFactor) {
this._changeROI({ xMagFactor,
/**
* getMagFactor:
- * @return an array, [xMagFactor, yMagFactor], containing the horizontal
- * and vertical magnification powers. A value of 1.0 means no
- * magnification. A value of 2.0 means the contents are doubled
- * in size, and so on.
+ * @returns {number[]} an array, [xMagFactor, yMagFactor], containing
+ * the horizontal and vertical magnification powers. A value of
+ * 1.0 means no magnification. A value of 2.0 means the contents
+ * are doubled in size, and so on.
*/
getMagFactor() {
return [this._xMagFactor, this._yMagFactor];
/**
* setMouseTrackingMode
- * @mode: One of the enum MouseTrackingMode values.
+ * @param {GDesktopEnums.MagnifierMouseTrackingMode} mode: the new mode
*/
setMouseTrackingMode(mode) {
if (mode >= GDesktopEnums.MagnifierMouseTrackingMode.NONE &&
/**
* getMouseTrackingMode
- * @return: One of the enum MouseTrackingMode values.
+ * @returns {GDesktopEnums.MagnifierMouseTrackingMode} the current mode
*/
getMouseTrackingMode() {
return this._mouseTrackingMode;
/**
* setFocusTrackingMode
- * @mode: One of the enum FocusTrackingMode values.
+ * @param {GDesktopEnums.MagnifierFocusTrackingMode} mode: the new mode
*/
setFocusTrackingMode(mode) {
this._focusTrackingMode = mode;
/**
* setCaretTrackingMode
- * @mode: One of the enum CaretTrackingMode values.
+ * @param {GDesktopEnums.MagnifierCaretTrackingMode} mode: the new mode
*/
setCaretTrackingMode(mode) {
this._caretTrackingMode = mode;
/**
* setViewPort
* Sets the position and size of the ZoomRegion on screen.
- * @viewPort: Object defining the position and size of the view port.
- * It has members x, y, width, height. The values are in
- * stage coordinate space.
+ * @param {{x: number, y: number, width: number, height: number}} viewPort:
+ * Object defining the position and size of the view port.
+ * The values are in stage coordinate space.
*/
setViewPort(viewPort) {
this._setViewPort(viewPort);
/**
* setROI
* Sets the "region of interest" that the ZoomRegion is magnifying.
- * @roi: Object that defines the region of the screen to magnify. It
- * has members x, y, width, height. The values are in
- * screen (unmagnified) coordinate space.
+ * @param {{x: number, y: number, width: number, height: number}} roi:
+ * Object that defines the region of the screen to magnify.
+ * The values are in screen (unmagnified) coordinate space.
*/
setROI(roi) {
if (roi.width <= 0 || roi.height <= 0)
* Retrieves the "region of interest" -- the rectangular bounds of that part
* of the desktop that the magnified view is showing (x, y, width, height).
* The bounds are given in non-magnified coordinates.
- * @return an array, [x, y, width, height], representing the bounding
- * rectangle of what is shown in the magnified view.
+ * @returns {number[]} an array, [x, y, width, height], representing
+ * the bounding rectangle of what is shown in the magnified view.
*/
getROI() {
let roiWidth = this._viewPortWidth / this._xMagFactor;
* setLensMode:
* Turn lens mode on/off. In full screen mode, lens mode does nothing since
* a lens the size of the screen is pointless.
- * @lensMode: A boolean to set the sense of lens mode.
+ * @param {bool} lensMode: Whether lensMode should be active
*/
setLensMode(lensMode) {
this._lensMode = lensMode;
/**
* isLensMode:
* Is lens mode on or off?
- * @return The lens mode state as a boolean.
+ * @returns {bool} The lens mode state.
*/
isLensMode() {
return this._lensMode;
* setClampScrollingAtEdges:
* Stop vs. allow scrolling of the magnified contents when it scroll beyond
* the edges of the screen.
- * @clamp: Boolean to turn on/off clamping.
+ * @param {bool} clamp: Boolean to turn on/off clamping.
*/
setClampScrollingAtEdges(clamp) {
this._clampScrollingAtEdges = clamp;
* setScreenPosition:
* Positions the zoom region to one of the enumerated positions on the
* screen.
- * @position: one of Magnifier.FULL_SCREEN, Magnifier.TOP_HALF,
- * Magnifier.BOTTOM_HALF,Magnifier.LEFT_HALF, or
- * Magnifier.RIGHT_HALF.
+ * @param {GDesktopEnums.MagnifierScreenPosition} inPosition: the position
*/
setScreenPosition(inPosition) {
switch (inPosition) {
* getScreenPosition:
* Tell the outside world what the current mode is -- magnifiying the
* top half, bottom half, etc.
- * @return: the current mode.
+ * @returns {GDesktopEnums.MagnifierScreenPosition}: the current position.
*/
getScreenPosition() {
return this._screenPosition;
/**
* scrollToMousePos:
* Set the region of interest based on the position of the system pointer.
- * @return: Whether the system mouse pointer is over the magnified view.
+ * @returns {bool}: Whether the system mouse pointer is over the
+ * magnified view.
*/
scrollToMousePos() {
this._followingCursor = true;
* scrollContentsTo:
* Shift the contents of the magnified view such it is centered on the given
* coordinate.
- * @x: The x-coord of the point to center on.
- * @y: The y-coord of the point to center on.
+ * @param {number} x: The x-coord of the point to center on.
+ * @param {number} y: The y-coord of the point to center on.
*/
scrollContentsTo(x, y) {
this._clearScrollContentsTimer();
/**
* addCrosshairs:
* Add crosshairs centered on the magnified mouse.
- * @crossHairs: Crosshairs instance
+ * @param {Crosshairs} crossHairs: Crosshairs instance
*/
addCrosshairs(crossHairs) {
this._crossHairs = crossHairs;
/**
* setInvertLightness:
* Set whether to invert the lightness of the magnified view.
- * @flag Boolean to either invert brightness (true), or not (false).
+ * @param {bool} flag: whether brightness should be inverted
*/
setInvertLightness(flag) {
this._invertLightness = flag;
/**
* getInvertLightness:
* Retrieve whether the lightness is inverted.
- * @return Boolean indicating inversion (true), or not (false).
+ * @returns {bool} whether brightness should be inverted
*/
getInvertLightness() {
return this._invertLightness;
/**
* setColorSaturation:
* Set the color saturation of the magnified view.
- * @sauration A value from 0.0 to 1.0 that defines the color
- * saturation, with 0.0 defining no color (grayscale),
- * and 1.0 defining full color.
+ * @param {number} saturation: A value from 0.0 to 1.0 that defines
+ * the color saturation, with 0.0 defining no color (grayscale),
+ * and 1.0 defining full color.
*/
setColorSaturation(saturation) {
this._colorSaturation = saturation;
/**
* getColorSaturation:
* Retrieve the color saturation of the magnified view.
+ * @returns {number} the color saturation
*/
getColorSaturation() {
return this._colorSaturation;
/**
* setBrightness:
* Alter the brightness of the magnified view.
- * @brightness Object containing the contrast for the red, green,
- * and blue channels. Values of 0.0 represent "standard"
- * brightness (no change), whereas values less or greater than
- * 0.0 indicate decreased or incresaed brightness, respectively.
+ * @param {Object} brightness: Object containing the contrast for the
+ * red, green, and blue channels. Values of 0.0 represent "standard"
+ * brightness (no change), whereas values less or greater than
+ * 0.0 indicate decreased or incresaed brightness, respectively.
+ *
+ * {number} brightness.r - the red component
+ * {number} brightness.g - the green component
+ * {number} brightness.b - the blue component
*/
setBrightness(brightness) {
this._brightness.r = brightness.r;
/**
* setContrast:
* Alter the contrast of the magnified view.
- * @contrast Object containing the contrast for the red, green,
- * and blue channels. Values of 0.0 represent "standard"
- * contrast (no change), whereas values less or greater than
- * 0.0 indicate decreased or incresaed contrast, respectively.
+ * @param {Object} contrast: Object containing the contrast for the
+ * red, green, and blue channels. Values of 0.0 represent "standard"
+ * contrast (no change), whereas values less or greater than
+ * 0.0 indicate decreased or incresaed contrast, respectively.
+ *
+ * {number} contrast.r - the red component
+ * {number} contrast.g - the green component
+ * {number} contrast.b - the blue component
*/
setContrast(contrast) {
this._contrast.r = contrast.r;
/**
* getContrast:
* Retrieve the contrast of the magnified view.
- * @return Object containing the contrast for the red, green,
- * and blue channels.
+ * @returns {{r: number, g: number, b: number}}: Object containing
+ * the contrast for the red, green, and blue channels.
*/
getContrast() {
let contrast = {};
* already part of some other ZoomRegion, create a clone of the crosshairs
* actor, and add the clone instead. Returns either the original or the
* clone.
- * @zoomRegion: The container to add the crosshairs group to.
- * @magnifiedMouse: The mouse actor for the zoom region -- used to
- * position the crosshairs and properly layer them below
- * the mouse.
- * @return The crosshairs actor, or its clone.
+ * @param {ZoomRegion} zoomRegion: The container to add the crosshairs
+ * group to.
+ * @param {Clutter.Actor} magnifiedMouse: The mouse actor for the
+ * zoom region -- used to position the crosshairs and properly
+ * layer them below the mouse.
+ * @returns {Clutter.Actor} The crosshairs actor, or its clone.
*/
addToZoomRegion(zoomRegion, magnifiedMouse) {
let crosshairsActor = null;
/**
* removeFromParent:
- * @childActor: the actor returned from addToZoomRegion
+ * @param {Clutter.Actor} childActor: the actor returned from
+ * addToZoomRegion
* Remove the crosshairs actor from its parent container, or destroy the
* child actor if it was just a clone of the crosshairs actor.
*/
/**
* setColor:
* Set the color of the crosshairs.
- * @clutterColor: The color as a Clutter.Color.
+ * @param {Clutter.Color} clutterColor: The color
*/
setColor(clutterColor) {
this._horizLeftHair.background_color = clutterColor;
/**
* getColor:
* Get the color of the crosshairs.
- * @color: The color as a Clutter.Color.
+ * @returns {ClutterColor} the crosshairs color
*/
getColor() {
return this._horizLeftHair.get_color();
/**
* setThickness:
* Set the width of the vertical and horizontal lines of the crosshairs.
- * @thickness
+ * @param {number} thickness: the new thickness value
*/
setThickness(thickness) {
this._horizLeftHair.set_height(thickness);
/**
* getThickness:
* Get the width of the vertical and horizontal lines of the crosshairs.
- * @return: The thickness of the crosshairs.
+ * @returns {number} The thickness of the crosshairs.
*/
getThickness() {
return this._horizLeftHair.get_height();
/**
* setOpacity:
* Set how opaque the crosshairs are.
- * @opacity: Value between 0 (fully transparent) and 255 (full opaque).
+ * @param {number} opacity: Value between 0 (fully transparent)
+ * and 255 (full opaque).
*/
setOpacity(opacity) {
// set_opacity() throws an exception for values outside the range
/**
* setLength:
* Set the length of the vertical and horizontal lines in the crosshairs.
- * @length: The length of the crosshairs.
+ * @param {number} length: The length of the crosshairs.
*/
setLength(length) {
this._horizLeftHair.set_width(length);
/**
* getLength:
* Get the length of the vertical and horizontal lines in the crosshairs.
- * @return: The length of the crosshairs.
+ * @returns {number} The length of the crosshairs.
*/
getLength() {
return this._horizLeftHair.get_width();
* setClip:
* Set the width and height of the rectangle that clips the crosshairs at
* their intersection
- * @size: Array of [width, height] defining the size of the clip
- * rectangle.
+ * @param {number[]} size: Array of [width, height] defining the size
+ * of the clip rectangle.
*/
setClip(size) {
if (size) {
* Reposition the horizontal and vertical hairs such that they cross at
* the center of crosshairs group. If called with the dimensions of
* the clip rectangle, these are used to update the size of the clip.
- * @clipSize: Optional. If present, an array of the form [width, height].
+ * @param {number[]=} clipSize: If present, the clip's [width, height].
*/
reCenter(clipSize) {
let [groupWidth, groupHeight] = this.get_size();
/**
* setInvertLightness:
* Enable/disable invert lightness effect.
- * @invertFlag: Enabled flag.
+ * @param {bool} invertFlag: Enabled flag.
*/
setInvertLightness(invertFlag) {
this._inverse.set_enabled(invertFlag);
/**
* setBrightness:
* Set the brightness of the magnified view.
- * @brightness: Object containing the brightness for the red, green,
- * and blue channels. Values of 0.0 represent "standard"
- * brightness (no change), whereas values less or greater than
- * 0.0 indicate decreased or incresaed brightness,
- * respectively.
+ * @param {Object} brightness: Object containing the contrast for the
+ * red, green, and blue channels. Values of 0.0 represent "standard"
+ * brightness (no change), whereas values less or greater than
+ * 0.0 indicate decreased or incresaed brightness, respectively.
+ *
+ * {number} brightness.r - the red component
+ * {number} brightness.g - the green component
+ * {number} brightness.b - the blue component
*/
setBrightness(brightness) {
let bRed = brightness.r;
/**
* Set the contrast of the magnified view.
- * @contrast: Object containing the contrast for the red, green,
- * and blue channels. Values of 0.0 represent "standard"
- * contrast (no change), whereas values less or greater than
- * 0.0 indicate decreased or incresaed contrast, respectively.
+ * @param {Object} contrast: Object containing the contrast for the
+ * red, green, and blue channels. Values of 0.0 represent "standard"
+ * contrast (no change), whereas values less or greater than
+ * 0.0 indicate decreased or incresaed contrast, respectively.
+ *
+ * {number} contrast.r - the red component
+ * {number} contrast.g - the green component
+ * {number} contrast.b - the blue component
*/
setContrast(contrast) {
let cRed = contrast.r;
/**
* setActive:
- * @activate: Boolean to activate or de-activate the magnifier.
+ * @param {bool} activate: activate or de-activate the magnifier.
*/
setActive(activate) {
Main.magnifier.setActive(activate);
/**
* isActive:
- * @return Whether the magnifier is active (boolean).
+ * @returns {bool} Whether the magnifier is active.
*/
isActive() {
return Main.magnifier.isActive();
/**
* createZoomRegion:
* Create a new ZoomRegion and return its object path.
- * @xMagFactor: The power to set horizontal magnification of the
- * ZoomRegion. A value of 1.0 means no magnification. A
- * value of 2.0 doubles the size.
- * @yMagFactor: The power to set the vertical magnification of the
- * ZoomRegion.
- * @roi Array of integers defining the region of the
- * screen/desktop to magnify. The array has the form
- * [left, top, right, bottom].
- * @viewPort Array of integers, [left, top, right, bottom] that defines
- * the position of the ZoomRegion on screen.
+ * @param {number} xMagFactor:
+ * The power to set horizontal magnification of the ZoomRegion.
+ * A value of 1.0 means no magnification. A value of 2.0 doubles
+ * the size.
+ * @param {number} yMagFactor:
+ * The power to set the vertical magnification of the
+ * ZoomRegion.
+ * @param {number[]} roi
+ * Array of integers defining the region of the screen/desktop
+ * to magnify. The array has the form [left, top, right, bottom].
+ * @param {number[]} viewPort
+ * Array of integers, [left, top, right, bottom] that defines
+ * the position of the ZoomRegion on screen.
*
* FIXME: The arguments here are redundant, since the width and height of
* the ROI are determined by the viewport and magnification factors.
* We ignore the passed in width and height.
*
- * @return The newly created ZoomRegion.
+ * @returns {ZoomRegion} The newly created ZoomRegion.
*/
createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) {
let ROI = { x: roi[0], y: roi[1], width: roi[2] - roi[0], height: roi[3] - roi[1] };
/**
* addZoomRegion:
* Append the given ZoomRegion to the magnifier's list of ZoomRegions.
- * @zoomerObjectPath: The object path for the zoom region proxy.
+ * @param {string} zoomerObjectPath: The object path for the zoom
+ * region proxy.
+ * @returns {bool} whether the region was added successfully
*/
addZoomRegion(zoomerObjectPath) {
let proxyAndZoomRegion = this._zoomers[zoomerObjectPath];
/**
* getZoomRegions:
* Return a list of ZoomRegion object paths for this Magnifier.
- * @return: The Magnifier's zoom region list as an array of DBus object
- * paths.
+ * @returns {string[]}: The Magnifier's zoom region list as an array
+ * of DBus object paths.
*/
getZoomRegions() {
// There may be more ZoomRegions in the magnifier itself than have
/**
* fullScreenCapable:
* Consult if the Magnifier can magnify in full-screen mode.
- * @return Always return true.
+ * @returns {bool} Always return true.
*/
fullScreenCapable() {
return true;
/**
* setCrosswireSize:
* Set the crosswire size of all ZoomRegions.
- * @size: The thickness of each line in the cross wire.
+ * @param {number} size: The thickness of each line in the cross wire.
*/
setCrosswireSize(size) {
Main.magnifier.setCrosshairsThickness(size);
/**
* getCrosswireSize:
* Get the crosswire size of all ZoomRegions.
- * @return: The thickness of each line in the cross wire.
+ * @returns {number}: The thickness of each line in the cross wire.
*/
getCrosswireSize() {
return Main.magnifier.getCrosshairsThickness();
/**
* setCrosswireLength:
* Set the crosswire length of all zoom-regions..
- * @size: The length of each line in the cross wire.
+ * @param {number} length: The length of each line in the cross wire.
*/
setCrosswireLength(length) {
Main.magnifier.setCrosshairsLength(length);
}
/**
- * setCrosswireSize:
- * Set the crosswire size of all zoom-regions.
- * @size: The thickness of each line in the cross wire.
+ * getCrosswireSize:
+ * Get the crosswire length of all zoom-regions.
+ * @returns {number} size: The length of each line in the cross wire.
*/
getCrosswireLength() {
return Main.magnifier.getCrosshairsLength();
/**
* setCrosswireClip:
* Set if the crosswire will be clipped by the cursor image..
- * @clip: Flag to indicate whether to clip the crosswire.
+ * @param {bool} clip: Flag to indicate whether to clip the crosswire.
*/
setCrosswireClip(clip) {
Main.magnifier.setCrosshairsClip(clip);
/**
* getCrosswireClip:
* Get the crosswire clip value.
- * @return: Whether the crosswire is clipped by the cursor image.
+ * @returns {bool}: Whether the crosswire is clipped by the cursor image.
*/
getCrosswireClip() {
return Main.magnifier.getCrosshairsClip();
/**
* setCrosswireColor:
* Set the crosswire color of all ZoomRegions.
- * @color: Unsigned int of the form rrggbbaa.
+ * @param {number} color: Unsigned int of the form rrggbbaa.
*/
setCrosswireColor(color) {
Main.magnifier.setCrosshairsColor('#%08x'.format(color));
/**
* getCrosswireClip:
* Get the crosswire color of all ZoomRegions.
- * @return: The crosswire color as an unsigned int in the form rrggbbaa.
+ * @returns {number}: The crosswire color as an unsigned int in
+ * the form rrggbbaa.
*/
getCrosswireColor() {
let colorString = Main.magnifier.getCrosshairsColor();
/**
* setMagFactor:
- * @xMagFactor: The power to set the horizontal magnification factor to
- * of the magnified view. A value of 1.0 means no
- * magnification. A value of 2.0 doubles the size.
- * @yMagFactor: The power to set the vertical magnification factor to
- * of the magnified view.
+ * @param {number} xMagFactor: The power to set the horizontal
+ * magnification factor to of the magnified view. A value of
+ * 1.0 means no magnification. A value of 2.0 doubles the size.
+ * @param {number} yMagFactor: The power to set the vertical
+ * magnification factor to of the magnified view.
*/
setMagFactor(xMagFactor, yMagFactor) {
this._zoomRegion.setMagFactor(xMagFactor, yMagFactor);
/**
* getMagFactor:
- * @return an array, [xMagFactor, yMagFactor], containing the horizontal
+ * @returns {number[]}: [xMagFactor, yMagFactor], containing the horizontal
* and vertical magnification powers. A value of 1.0 means no
* magnification. A value of 2.0 means the contents are doubled
* in size, and so on.
/**
* setRoi:
* Sets the "region of interest" that the ZoomRegion is magnifying.
- * @roi Array, [left, top, right, bottom], defining the region of the
- * screen to magnify. The values are in screen (unmagnified)
- * coordinate space.
+ * @param {number[]} roi: [left, top, right, bottom], defining the
+ * region of the screen to magnify.
+ * The values are in screen (unmagnified) coordinate space.
*/
setRoi(roi) {
let roiObject = { x: roi[0], y: roi[1], width: roi[2] - roi[0], height: roi[3] - roi[1] };
* Retrieves the "region of interest" -- the rectangular bounds of that part
* of the desktop that the magnified view is showing (x, y, width, height).
* The bounds are given in non-magnified coordinates.
- * @return an array, [left, top, right, bottom], representing the bounding
+ * @returns {Array}: [left, top, right, bottom], representing the bounding
* rectangle of what is shown in the magnified view.
*/
getRoi() {
/**
* Set the "region of interest" by centering the given screen coordinate
* within the zoom region.
- * @x The x-coord of the point to place at the center of the zoom region.
- * @y The y-coord.
- * @return Whether the shift was successful (for GS-mag, this is always
- * true).
+ * @param {number} x: The x-coord of the point to place at the
+ * center of the zoom region.
+ * @param {number} y: The y-coord.
+ * @returns {bool} Whether the shift was successful (for GS-mag, this
+ * is always true).
*/
shiftContentsTo(x, y) {
this._zoomRegion.scrollContentsTo(x, y);
/**
* moveResize
* Sets the position and size of the ZoomRegion on screen.
- * @viewPort Array, [left, top, right, bottom], defining the position and
- * size on screen to place the zoom region.
+ * @param {number[]} viewPort: [left, top, right, bottom], defining
+ * the position and size on screen to place the zoom region.
*/
moveResize(viewPort) {
let viewRect = { x: viewPort[0], y: viewPort[1], width: viewPort[2] - viewPort[0], height: viewPort[3] - viewPort[1] };
*
* Get the theme CSS file that the shell will load
*
- * Returns: A #GFile that contains the theme CSS,
+ * @returns {?Gio.File}: A #GFile that contains the theme CSS,
* null if using the default
*/
function getThemeStylesheet() {
/**
* setThemeStylesheet:
- * @cssStylesheet: A file path that contains the theme CSS,
- * set it to null to use the default
+ * @param {string=} cssStylesheet: A file path that contains the theme CSS,
+ * set it to null to use the default
*
* Set the theme CSS file that the shell will load
*/
/**
* notify:
- * @msg: A message
- * @details: Additional information
+ * @param {string} msg: A message
+ * @param {string} details: Additional information
*/
function notify(msg, details) {
let source = new MessageTray.SystemNotificationSource();
/**
* notifyError:
- * @msg: An error message
- * @details: Additional information
+ * @param {string} msg: An error message
+ * @param {string} details: Additional information
*
* See shell_global_notify_problem().
*/
/**
* pushModal:
- * @actor: #ClutterActor which will be given keyboard focus
- * @params: optional parameters
+ * @param {Clutter.Actor} actor: actor which will be given keyboard focus
+ * @param {Object=} params: optional parameters
*
* Ensure we are in a mode where all keyboard and mouse input goes to
* the stage, and focus @actor. Multiple calls to this function act in
* global keybindings; the default of NONE will filter
* out all keybindings
*
- * Returns: true iff we successfully acquired a grab or already had one
+ * @returns {bool}: true iff we successfully acquired a grab or already had one
*/
function pushModal(actor, params) {
params = Params.parse(params, { timestamp: global.get_current_time(),
/**
* popModal:
- * @actor: #ClutterActor passed to original invocation of pushModal()
- * @timestamp: optional timestamp
+ * @param {Clutter.Actor} actor: the actor passed to original invocation
+ * of pushModal()
+ * @param {number=} timestamp: optional timestamp
*
* Reverse the effect of pushModal(). If this invocation is undoing
* the topmost invocation, then the focus will be restored to the
/**
* activateWindow:
- * @window: the Meta.Window to activate
- * @time: (optional) current event time
- * @workspaceNum: (optional) window's workspace number
+ * @param {Meta.Window} window: the window to activate
+ * @param {number=} time: current event time
+ * @param {number=} workspaceNum: window's workspace number
*
* Activates @window, switching to its workspace first if necessary,
* and switching out of the overview if it's currently active
/**
* initializeDeferredWork:
- * @actor: A #ClutterActor
- * @callback: Function to invoke to perform work
+ * @param {Clutter.Actor} actor: an actor
+ * @param {callback} callback: Function to invoke to perform work
*
* This function sets up a callback to be invoked when either the
* given actor is mapped, or after some period of time when the machine
* initialization as well, under the assumption that new actors
* will need it.
*
- * Returns: A string work identifier
+ * @returns {string}: A string work identifier
*/
function initializeDeferredWork(actor, callback) {
// Turn into a string so we can use as an object property
/**
* queueDeferredWork:
- * @workId: work identifier
+ * @param {string} workId: work identifier
*
* Ensure that the work identified by @workId will be
* run on map or timeout. You should call this function
}
/**
- * @side Side to which the arrow points.
+ * arrowIcon
+ * @param {St.Side} side - Side to which the arrow points.
+ * @returns {St.Icon} a new arrow icon
*/
function arrowIcon(side) {
let iconName;
/**
* sleep:
- * @milliseconds: number of milliseconds to wait
+ * @param {number} milliseconds - number of milliseconds to wait
+ * @returns {Promise} that resolves after @milliseconds ms
*
* Used within an automation script to pause the the execution of the
* current script for the specified amount of time. Use as
/**
* waitLeisure:
+ * @returns {Promise} that resolves when the shell is idle
*
* Used within an automation script to pause the the execution of the
* current script until the shell is completely idle. Use as
/**
* createTestWindow:
- * @params: options for window creation.
- * width - width of window, in pixels (default 640)
- * height - height of window, in pixels (default 480)
- * alpha - whether the window should have an alpha channel (default false)
- * maximized - whether the window should be created maximized (default false)
- * redraws - whether the window should continually redraw itself (default false)
- * @maximized: whethe the window should be created maximized
+ * @param {Object} params: options for window creation.
+ * {number} [params.width=640] - width of window, in pixels
+ * {number} [params.height=480] - height of window, in pixels
+ * {bool} [params.alpha=false] - whether the window should have an alpha channel
+ * {bool} [params.maximized=false] - whether the window should be created maximized
+ * {bool} [params.redraws=false] - whether the window should continually redraw itself
+ * @returns {Promise}
*
* Creates a window using gnome-shell-perf-helper for testing purposes.
* While this function can be used with yield in an automation
/**
* waitTestWindows:
+ * @returns {Promise}
*
* Used within an automation script to pause until all windows previously
* created with createTestWindow have been mapped and exposed.
/**
* destroyTestWindows:
+ * @returns {Promise}
*
* Destroys all windows previously created with createTestWindow().
* While this function can be used with yield in an automation
/**
* defineScriptEvent
- * @name: The event will be called script.<name>
- * @description: Short human-readable description of the event
+ * @param {string} name: The event will be called script.<name>
+ * @param {string} description: Short human-readable description of the event
*
* Convenience function to define a zero-argument performance event
* within the 'script' namespace that is reserved for events defined locally
/**
* scriptEvent
- * @name: Name registered with defineScriptEvent()
+ * @param {string} name: Name registered with defineScriptEvent()
*
* Convenience function to record a script-local performance event
* previously defined with defineScriptEvent
/**
* runPerfScript
- * @scriptModule: module object with run and finish functions
- * and event handlers
+ * @param {Object} scriptModule: module object with run and finish
+ * functions and event handlers
+ * @param {string} outputFile: path to write output to
*
* Runs a script for automated collection of performance data. The
* script is defined as a Javascript module with specified contents.
/**
* Eval:
- * @code: A string containing JavaScript code
+ * @param {string} code: A string containing JavaScript code
+ * @returns {Array}
*
* This function executes arbitrary code in the main
* loop, and returns a boolean success and
/**
* AskPassword:
- * @id: an opaque ID identifying the object for which the operation is requested
- * The ID must be unique in the context of the calling process.
- * @message: the message to display
- * @icon_name: the name of an icon to display
- * @default_user: the default username for display
- * @default_domain: the default domain for display
- * @flags: a set of GAskPasswordFlags
- * @response: a GMountOperationResult
- * @response_details: a dictionary containing the response details as
- * entered by the user. The dictionary MAY contain the following properties:
+ * @param {Array} params
+ * {string} id: an opaque ID identifying the object for which
+ * the operation is requested
+ * {string} message: the message to display
+ * {string} icon_name: the name of an icon to display
+ * {string} default_user: the default username for display
+ * {string} default_domain: the default domain for display
+ * {Gio.AskPasswordFlags} flags: a set of GAskPasswordFlags
+ * {Gio.MountOperationResults} response: a GMountOperationResult
+ * {Object} response_details: a dictionary containing response details as
+ * entered by the user. The dictionary MAY contain the following
+ * properties:
* - "password" -> (s): a password to be used to complete the mount operation
* - "password_save" -> (u): a GPasswordSave
+ * @param {Gio.DBusMethodInvocation} invocation
+ * The ID must be unique in the context of the calling process.
*
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
/**
* AskQuestion:
- * @id: an opaque ID identifying the object for which the operation is requested
+ * @param {Array} params - params
+ * {string} id: an opaque ID identifying the object for which
+ * the operation is requested
* The ID must be unique in the context of the calling process.
- * @message: the message to display
- * @icon_name: the name of an icon to display
- * @choices: an array of choice strings
- * GetResponse:
- * @response: a GMountOperationResult
- * @response_details: a dictionary containing the response details as
- * entered by the user. The dictionary MAY contain the following properties:
- * - "choice" -> (i): the chosen answer among the array of strings passed in
+ * {string} message: the message to display
+ * {string} icon_name: the name of an icon to display
+ * {string[]} choices: an array of choice strings
+ * @param {Gio.DBusMethodInvocation} invocation - invocation
*
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
/**
* ShowProcesses:
- * @id: an opaque ID identifying the object for which the operation is requested
+ * @param {Array} params - params
+ * {string} id: an opaque ID identifying the object for which
+ * the operation is requested
* The ID must be unique in the context of the calling process.
- * @message: the message to display
- * @icon_name: the name of an icon to display
- * @application_pids: the PIDs of the applications to display
- * @choices: an array of choice strings
- * @response: a GMountOperationResult
- * @response_details: a dictionary containing the response details as
- * entered by the user. The dictionary MAY contain the following properties:
- * - "choice" -> (i): the chosen answer among the array of strings passed in
+ * {string} message: the message to display
+ * {string} icon_name: the name of an icon to display
+ * {number[]} application_pids: the PIDs of the applications to display
+ * {string[]} choices: an array of choice strings
+ * @param {Gio.DBusMethodInvocation} invocation - invocation
*
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
/**
* Close:
+ * @param {Array} _params - params
+ * @param {Gio.DBusMethodInvocation} _invocation - invocation
*
* Closes a dialog previously opened by AskPassword, AskQuestion or ShowProcesses.
* If no dialog is open, does nothing.
projects / gnome-shell.git / commitdiff